You are here: Errors Reference > Documaker Standard Edition > Documaker Errors > Creating Messages > Setting Up Message Text

Setting Up Message Text

Message output from system programs is typically destination bound to the error or log files. All static message text is isolated into an external file for easy maintenance. The static portion of all messages is contained in the XLTUS.MSG file on Windows and UNIX or the TRANSLAT.INI file.on z/OS.

The INI designation is one of convenience, since the TRANSLAT.INI file is not intended to be used like a conventional INI file. INI references intended for other program functionality do not work when placed in this file. Likewise, you cannot add static message text intended for the log or error files into the FSISYS.INI or FSIUSER.INI files.

All messages must have a unique message number. You must ensure the proper message number is referenced in the code.

Message examples

Here are some examples from the XLTUS.MSG file:

10529, 42, "%1:  %2 in RunDate(): Unable to GENFmtDate(<%3>,,)."

10536, 42, "%1:  %2 in LookUp(): Missing Key offset in LookUp."

20261, 42, "\nProcessing Batch:<%1> File:<%2> Port:<%3>\n"

Here are the corresponding examples from the TRANSLAT.INI file:

10529 = &E&:  &MTYPE& in RunDate(): Unable to GENFmtDate(<&RunDate&>,,).

10536 = &E&:  &MTYPE& in LookUp(): Missing Key offset in LookUp.

20261 = \nProcessing Batch:<&Name&> File:<&File&> Port:<&Print&>

There are several points to note in these messages.

Each line specifies a unique message number and associates the static text portion of the message with that number.
In the XLTUS.MSG file, %1, %2, %3, and so on, are token placeholders for value replacement. In the TRANSLAT.INI file, the words bounded on each end with an ampersand (&) are token placeholders for value replacement.

This is where the token-data pairs passed to the RPErrorProc and RPLogProc functions are matched and substituted into the static text. For example, assume the following statement is in the code of one of the system programs.

RPErrorProc(pRPS, (WORD)EMIT_ERROR, (DWORD)10529,

"RunDate", “April 1, 1999”,

LASTERRORTOKEN);

This would cause message number 10529, shown above, to print this text in the log file.

Error in rundate(): Unable to GENFmtDate(<April 1, 1999>,,).

Since token names are identified between ampersand characters, two ampersand characters together (&&) signals that the output text is to contain a single ampersand character.

Undefined tokens

Notice there are three substitution variables in the 10529 message but only one substitution pair is passed to the RPErrorProc function.

The TRANSLAT.MMP file contains three substitution variables (%1, %2, %3) for message 10529.

10529:E,MTYPE,RunDate,

E and MTYPE in the TRANSLAT.MMP file (or &E& and &MTYPE& in the TRANSLAT.INI file on z/OS) are substitution variables that are automatically handled by the RPErrorProc function.

A warning message is generated when EMIT_MESSAGE is passed as the second parameter to RPErrorProc and the MTYPE substitution variable is replaced with the string, Warning.

An error message is generated when EMIT_ERROR is passed as the second parameter to RPErrorProc and the MTYPE substitution variable is replaced with the string, Error.

An error message is also generated when EMIT_CRITICAL is passed as the second parameter to RPErrorProc and the MTYPE substitution variable is replaced with the string, Critical Error.

Messages can have any number of token replacements. If, however, a token is undefined when the messages are translated, the token name is left in the text. So, if you view the log or error file and find a message which includes a word bounded by ampersands, it means one of these things:

The token is misspelled in the message file.
The token is misspelled in the code that called the RPLogProc or RPErrorProc function.
The token and data was not included in the parameters to the message functions.
This is not a token and was intended to print in this manner. Either it is data associated with a token or two ampersands were included at each end of the word in the static message text.

The first place to begin diagnosing this type of result is by examining the text included for the message in the XLTUS.MSG or TRANSLAT.INI file.

Adding a new line

In message number 20261, you can see the use of another format convention. The \n in the text is translated as a new line character. This causes the following text to print on the next line. The layout of the XLTUS.MSG or TRANSLAT.INI file requires that all of the text for each message must fit onto a single line. Using \n in text expands your formatting possibilities.

Determining where the message originated

Examine message number 20246. This message does not contain any tokens. Therefore there is no variable text that is required to print within this message.

The fact that the message does not contain any tokens does not mean that no tokens were output from the system program when the RPErrorProc function was called. In fact, there are at least two tokens associated with this message.

LASTERRORTOKEN is the last required parameter to calls to the RPErrorProc and RPLogProc functions. This macro defines the FSIFileName and FSILineNumber tokens. If you include the FSIFileName token in the message text, the name of the module that contained the code calling the RPErrorProc or RPLogProc function is substituted into the message. Likewise, FSILineNumber is substituted with the source line number of the statement calling the RPLogProc or RPErrorProc function.

This information can be quite useful if you are trying to determine what code is issuing a particular message. All you have to do is edit the message and include &FSILFileName& and &FSILineNumber& into the message text defined in the XLTUS.MSG or TRANSLAT.INI file.